home *** CD-ROM | disk | FTP | other *** search
/ SGI Performance Co-Pilot 1.3 / SGI Performance Co-Pilot 1.3.iso / dist / dist6.4 / pcp.idb / usr / share / catman / u_man / cat3 / PMAPI / pmfetch.z / pmfetch
Text File  |  1997-04-03  |  12KB  |  199 lines
  1.  
  2.  
  3.  
  4. PPPPMMMMFFFFEEEETTTTCCCCHHHH((((3333))))                                                          PPPPMMMMFFFFEEEETTTTCCCCHHHH((((3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      ppppmmmmFFFFeeeettttcccchhhh - get performance metric values
  10.  
  11. CCCC SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ppppccccpppp////ppppmmmmaaaappppiiii....hhhh>>>>
  13.  
  14.      iiiinnnntttt ppppmmmmFFFFeeeettttcccchhhh((((iiiinnnntttt nnnnuuuummmmppppmmmmiiiidddd,,,, ppppmmmmIIIIDDDD ppppmmmmiiiiddddlllliiiisssstttt[[[[]]]],,,, ppppmmmmRRRReeeessssuuuulllltttt ********rrrreeeessssuuuulllltttt))))
  15.  
  16.      cccccccc ............ ----llllppppccccpppp
  17.  
  18. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  19.      Given a list of Performance Metric IDs (PMID)s, e.g. as constructed by
  20.      ppppmmmmLLLLooooooookkkkuuuuppppNNNNaaaammmmeeee(3), via _p_m_i_d_l_i_s_t and _n_u_m_p_m_i_d, fetch the values for these
  21.      performance metrics.
  22.  
  23.      The call to ppppmmmmFFFFeeeettttcccchhhh is executed in the context of a source of metrics,
  24.      instance profile and collection time, previously established by calls to
  25.      the appropriate context and profile functions, namely some of
  26.      ppppmmmmNNNNeeeewwwwCCCCoooonnnntttteeeexxxxtttt(3), ppppmmmmDDDDuuuuppppCCCCoooonnnntttteeeexxxxtttt(3), ppppmmmmUUUUsssseeeeCCCCoooonnnntttteeeexxxxtttt(3), ppppmmmmAAAAddddddddPPPPrrrrooooffffiiiilllleeee(3),
  27.      ppppmmmmDDDDeeeellllPPPPrrrrooooffffiiiilllleeee(3) and ppppmmmmSSSSeeeettttMMMMooooddddeeee(3).
  28.  
  29.      The principal result from ppppmmmmFFFFeeeettttcccchhhh is returned in the argument _r_e_s_u_l_t as a
  30.      tree, using the following component data structures;
  31.  
  32.           typedef struct {
  33.                 int      len;                  /* length in bytes */
  34.                 char     vbuf[1];              /* one or more values */
  35.           } pmValueBlock;
  36.  
  37.           typedef struct {
  38.                 int      inst;                 /* instance identifier */
  39.                 union {
  40.                       pmValueBlock *pval;      /* pointer to value-block */
  41.                       int          lval;       /* integer value insitu */
  42.                 } value;
  43.           } pmValue;
  44.  
  45.           typedef struct {
  46.                 pmID      pmid;                /* metric identifier */
  47.                 int       numval;              /* number of values or error code */
  48.                 int       valfmt;              /* value style, insitu or ptr */
  49.                 pmValue   vlist[1];            /* set of instances/values */
  50.           } pmValueSet;
  51.  
  52.           /* Result returned by pmFetch() */
  53.           typedef struct {
  54.                 struct timeval timestamp;      /* time stamped by collector */
  55.                 int            numpmid;        /* number of PMIDs */
  56.                 pmValueSet     *vset[1];       /* set of value sets */
  57.           } pmResult;
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. PPPPMMMMFFFFEEEETTTTCCCCHHHH((((3333))))                                                          PPPPMMMMFFFFEEEETTTTCCCCHHHH((((3333))))
  71.  
  72.  
  73.  
  74.      To accommodate metrics with multiple value instances, the _n_u_m_v_a_l field
  75.      indicates how many values are returned for each requested PMID.  The
  76.      field _v_a_l_f_m_t in the _p_m_V_a_l_u_e_S_e_t structure indicates if the values for this
  77.      metric are stored _i_n_s_i_t_u in the _l_v_a_l field, i.e. a 32-bit quantity
  78.      (either long, unsigned long or float, or if the values are held in
  79.      associated _p_m_V_a_l_u_e_B_l_o_c_k structures. The _p_m_V_a_l_u_e_B_l_o_c_k structure can
  80.      accommodate arbitrary sized binary data, and is suited for `string-
  81.      valued' metrics and metrics with aggregated or complex data types.  It is
  82.      expected that the _i_n_s_i_t_u format will be the most common option.
  83.  
  84.      If one value (i.e. associated with a particular instance) for a requested
  85.      metric is `unavailable' (at the requested time), then there is no
  86.      associated _p_m_V_a_l_u_e structure in the _r_e_s_u_l_t.  If there are no available
  87.      values for a metric, then _n_u_m_v_a_l will be zero and the associated
  88.      _p_m_V_a_l_u_e[] instance will be empty (_v_a_l_f_m_t is undefined in these
  89.      circumstances, however _p_m_i_d will be correctly set to the PMID of the
  90.      metric with no values).
  91.  
  92.      As an extension of this protocol, if the Performance Metrics Collection
  93.      System (PMCS) is able to provide a reason why no values are available for
  94.      a particular metric, this is encoded as a standard error code in the
  95.      corresponding _n_u_m_v_a_l.  Since the error codes are all negative, values for
  96.      a requested metric are `unavailable' if _n_u_m_v_a_l is less than, or equal to,
  97.      zero.  A performance metric's value may be `unavailable' for any of the
  98.      following reasons;
  99.  
  100.      +  The metric is not supported in this version of the software for the
  101.         associated Performance Metric Domain
  102.  
  103.      +  Collection is not currently activated in the software for the
  104.         associated Performance Metric Domain
  105.  
  106.      +  The associated PMID is not known
  107.  
  108.      +  The current system configuration does not include the associated
  109.         hardware component and/or the associated software module, e.g. a disk
  110.         is not installed, or off-line, or Oracle is not installed
  111.  
  112.      +  The metric is one for which an instance profile is required, and none
  113.         was provided (there are a small number of metrics in this category,
  114.         typically ones with very large, and/or very dynamic instance domains,
  115.         and/or expensive metric instantiation methods).
  116.  
  117.      In general, we may not be able to differentiate between the various
  118.      cases, and if differentiation is not possible, _n_u_m_v_a_l will simply be
  119.      zero.
  120.  
  121.      The argument definition and the result specifications have been
  122.      constructed to ensure that for each PMID in the requested _p_m_i_d_l_i_s_t there
  123.      is exactly one _p_m_V_a_l_u_e_S_e_t in the _r_e_s_u_l_t, and further the PMIDs appear in
  124.      exactly the same sequence in both _p_m_i_d_l_i_s_t and _r_e_s_u_l_t.  This makes the
  125.      number and order of entries in _r_e_s_u_l_t completely deterministic, and
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. PPPPMMMMFFFFEEEETTTTCCCCHHHH((((3333))))                                                          PPPPMMMMFFFFEEEETTTTCCCCHHHH((((3333))))
  137.  
  138.  
  139.  
  140.      greatly simplifies the application programming logic after the call to
  141.      ppppmmmmFFFFeeeettttcccchhhh.
  142.  
  143.      The _r_e_s_u_l_t structure returned by ppppmmmmFFFFeeeettttcccchhhh is dynamically allocated using a
  144.      combination of mmmmaaaalllllllloooocccc(3C) calls and specialized allocation strategies,
  145.      and should be released when no longer required by calling ppppmmmmFFFFrrrreeeeeeeeRRRReeeessssuuuulllltttt(3)
  146.      - under no circumstances should ffffrrrreeeeeeee(3C) be called directly to release
  147.      this space.
  148.  
  149.      As common error conditions are encoded in the _r_e_s_u_l_t data structure, we'd
  150.      expect only cataclysmic events to cause an error value to be returned.
  151.      One example would be if the metrics source context was a remote host, and
  152.      that host or the PMCS on that host became unreachable.  Otherwise the
  153.      value returned by the ppppmmmmFFFFeeeettttcccchhhh function will be zero.
  154.  
  155. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  156.      ppppmmmmAAAAddddddddPPPPrrrrooooffffiiiilllleeee(3), PPPPMMMMAAAAPPPPIIII(3), ppppmmmmDDDDeeeellllPPPPrrrrooooffffiiiilllleeee(3), ppppmmmmDDDDuuuuppppCCCCoooonnnntttteeeexxxxtttt(3),
  157.      ppppmmmmEEEExxxxttttrrrraaaaccccttttVVVVaaaalllluuuueeee(3), ppppmmmmFFFFeeeettttcccchhhhAAAArrrrcccchhhhiiiivvvveeee(3), ppppmmmmFFFFrrrreeeeeeeeRRRReeeessssuuuulllltttt(3), ppppmmmmGGGGeeeettttIIIInnnnDDDDoooommmm(3),
  158.      ppppmmmmLLLLooooooookkkkuuuuppppDDDDeeeesssscccc(3), ppppmmmmLLLLooooooookkkkuuuuppppNNNNaaaammmmeeee(3), ppppmmmmNNNNeeeewwwwCCCCoooonnnntttteeeexxxxtttt(3), ppppmmmmSSSSeeeettttMMMMooooddddeeee(3),
  159.      ppppmmmmUUUUsssseeeeCCCCoooonnnntttteeeexxxxtttt(3) and ppppmmmmWWWWhhhhiiiicccchhhhCCCCoooonnnntttteeeexxxxtttt(3).
  160.  
  161.      Note that ppppmmmmFFFFeeeettttcccchhhh is the most primitive method of fetching metric values
  162.      from the PMCS.  More user friendly interfaces to the PMCS are available
  163.      or currently under development - these higher level fetch methods
  164.      insulate the user from the intricacies of context creation, setting up
  165.      instance profiles, _p_m_R_e_s_u_l_t traversal, and splitting fetches into batches
  166.      to minimize PDU traffic or according to other optimization criteria.
  167.  
  168. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  169.      As mentioned above, ppppmmmmFFFFeeeettttcccchhhh returns error codes _i_n_s_i_t_u in the argument
  170.      _r_e_s_u_l_t.  If no result is returned, e.g. due to IPC failure using the
  171.      current PMAPI context, or end of file on an archive log, then ppppmmmmFFFFeeeettttcccchhhh
  172.      will return a negative error code which may be examined using
  173.      ppppmmmmEEEErrrrrrrrSSSSttttrrrr(3).
  174.  
  175.      PPPPMMMM____EEEERRRRRRRR____EEEEOOOOLLLL
  176.           When fetching records from an archive log, ppppmmmmFFFFeeeettttcccchhhh returns this
  177.           error code to indicate the end of the log has been passed (or the
  178.           start of the log has been passed, if the direction of traversal is
  179.           backwards in time).  If the ``mode'' for the current PMAPI context
  180.           (see ppppmmmmSSSSeeeettttMMMMooooddddeeee(3)) is PPPPMMMM____MMMMOOOODDDDEEEE____IIIINNNNTTTTEEEERRRRPPPP then the time origin is
  181.           advanced, even when this error code is returned.  In this way
  182.           applications that position the time outside the range defined by the
  183.           records in the archive, and then commence to ppppmmmmFFFFeeeettttcccchhhh will eventually
  184.           see valid results once the time origin moves inside the temporal
  185.           span of the archive.
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.